<HTML>
<HEAD><TITLE>Widget</TITLE></HEAD>
<BODY BGCOLOR=white>
<IMG SRC="constr.gif" WIDTH="40" HEIGHT="40"> Under construction ...<BR>
<DL><DT><I><A HREF="#descr">NAME</A></I></DT>
<DD><B>Widget</B>
 - The Widget base class
</DD></DL>
<DL>
<DT><I><A HREF="#wc">COMMAND</A></I></DT>
<DD>Widget::<A HREF="#addmap"><B>addmap</B></A>
 <I>class</I>
 <I>subclass</I>
 <I>subpath</I>
 <I>options</I>
</DD>
<DD>Widget::<A HREF="#bwinclude"><B>bwinclude</B></A>
 <I>class</I>
 <I>subclass</I>
 <I>subpath</I>
 ?<I>arg...</I>?
</DD>
<DD>Widget::<A HREF="#cget"><B>cget</B></A>
 <I>path</I>
 <I>option</I>
</DD>
<DD>Widget::<A HREF="#configure"><B>configure</B></A>
 <I>path</I>
 <I>options</I>
</DD>
<DD>Widget::<A HREF="#create"><B>create</B></A>
 <I>class</I>
 <I>path</I>
 ?<I>rename</I>?
</DD>
<DD>Widget::<A HREF="#declare"><B>declare</B></A>
 <I>class</I>
 <I>optlist</I>
</DD>
<DD>Widget::<A HREF="#define"><B>define</B></A>
 <I>class</I>
 <I>filename</I>
 ?<I>class ...</I>?
</DD>
<DD>Widget::<A HREF="#destroy"><B>destroy</B></A>
 <I>path</I>
</DD>
<DD>Widget::<A HREF="#focusNext"><B>focusNext</B></A>
 <I>w</I>
</DD>
<DD>Widget::<A HREF="#focusOK"><B>focusOK</B></A>
 <I>w</I>
</DD>
<DD>Widget::<A HREF="#focusPrev"><B>focusPrev</B></A>
 <I>w</I>
</DD>
<DD>Widget::<A HREF="#generate-doc"><B>generate-doc</B></A>
 <I>dir</I>
 <I>widgetlist</I>
</DD>
<DD>Widget::<A HREF="#generate-widget-doc"><B>generate-widget-doc</B></A>
 <I>class</I>
 <I>iscmd</I>
 <I>file</I>
</DD>
<DD>Widget::<A HREF="#getoption"><B>getoption</B></A>
 <I>path</I>
 <I>option</I>
</DD>
<DD>Widget::<A HREF="#getVariable"><B>getVariable</B></A>
 <I>path</I>
 <I>varName</I>
 <I>?myVarName?</I>
</DD>
<DD>Widget::<A HREF="#hasChanged"><B>hasChanged</B></A>
 <I>path</I>
 <I>option</I>
 <I>pvalue</I>
</DD>
<DD>Widget::<A HREF="#init"><B>init</B></A>
 <I>class</I>
 <I>path</I>
 <I>options</I>
</DD>
<DD>Widget::<A HREF="#setoption"><B>setoption</B></A>
 <I>path</I>
 <I>option</I>
 <I>value</I>
</DD>
<DD>Widget::<A HREF="#subcget"><B>subcget</B></A>
 <I>path</I>
 <I>subwidget</I>
</DD>
<DD>Widget::<A HREF="#syncoptions"><B>syncoptions</B></A>
 <I>class</I>
 <I>subclass</I>
 <I>subpath</I>
 <I>options</I>
</DD>
<DD>Widget::<A HREF="#tkinclude"><B>tkinclude</B></A>
 <I>class</I>
 <I>tkwidget</I>
 <I>subpath</I>
 ?<I>arg...</I>?
</DD>
</DL>
<BR><HR WIDTH="100%"><BR>
<B><A NAME="descr"></A>DESCRIPTION</B><BR>
<P>

The <B>Widget</B> namespace handle data associated to all BWidget and provide commands
to easily define BWidget.
<BR>For commands can be used to define a BWidget:
<B>tkinclude</B>, <B>bwinclude</B>, <B>declare</B>, <B>addmap</B> and <B>syncoptions</B>.
Here is the definition of <A HREF="ComboBox.html">ComboBox</A> widget:
<BR><BR>
<CENTER>
<TABLE BORDER=2 CELSPACING=2 WIDTH=80%>
<TR><TD><PRE>
namespace eval ComboBox {
    <FONT COLOR=red><I># We're using ArrowButton, Entry and LabelFrame</I></FONT>
    ArrowButton::use
    Entry::use
    LabelFrame::use

    <FONT COLOR=red><I># Include resources of LabelFrame</I></FONT>
    Widget::bwinclude ComboBox LabelFrame .labf \ 
        rename     {-text -label} \ 
        remove     {-focus} \ 
        prefix     {label -justify -width -anchor -height -font} \ 
        initialize {-relief sunken -borderwidth 2}

    <FONT COLOR=red><I># Include resources of Entry</I></FONT>
    Widget::bwinclude ComboBox Entry .e \ 
        remove {-relief -bd -borderwidth -bg -fg} \ 
        rename {-foreground -entryfg -background -entrybg}

    <FONT COLOR=red><I># Declare new resources</I></FONT>
    Widget::declare ComboBox {
        {-height      TkResource 0  0 listbox}
        {-values      String     "" 0}
        {-modifycmd   String     "" 0}
        {-postcommand String     "" 0}
    }

    <FONT COLOR=red><I># Map resources to subwidget</I></FONT>
    Widget::addmap ComboBox "" :cmd {-background {}}
    Widget::addmap ComboBox ArrowButton .a \ 
        {-foreground {} -background {} -disabledforeground {} -state {}}

    <FONT COLOR=red><I># Synchronize subwidget options</I></FONT>
    Widget::syncoptions ComboBox Entry .e {-text {}}
    Widget::syncoptions ComboBox LabelFrame .labf {-label -text -underline {}}

    proc use {} {}
}</PRE>
</TD></TR>
</TABLE></CENTER>

</P>
<HR WIDTH="50%"><BR>
<B><A NAME="wc">COMMAND</A></B><BR>
<DL><DT><A NAME="addmap">Widget::<B>addmap</B></A>
 <I>class</I>
 <I>subclass</I>
 <I>subpath</I>
 <I>options</I>
</DT><DD>

This command map some resources to subwidget.
Mapped resources automatically configure subwidget when widget is configured.
<UL>
<LI><I>class</I> is the class of the new BWidget
<LI><I>subclass</I> is the class the subwidget (BWidget class, e.g Entry, or empty for Tk widget)
<LI><I>subpath</I> is the path of the subwidget
<LI><I>options</I> is the list <I>{option realres ...}</I> of options to map to subwidget
</UL>
</DD></DL>
<DL><DT><A NAME="bwinclude">Widget::<B>bwinclude</B></A>
 <I>class</I>
 <I>subclass</I>
 <I>subpath</I>
 ?<I>arg...</I>?
</DT><DD>

This command includes into a new BWidget the resources of another BWidget.
Arguments are:
<UL>
<LI><I>class</I> class of the new widget
<LI><I>subclass</I> class name of the BWidget to be included
<LI><I>subpath</I>  path of the widget to configure when BWidget is configured
<LI><I>options</I> is:
<UL>
<LI><I><B>include</B> {option option ...}</I>
<BR>list of options to include (all if not defined)
<LI><I><B>remove</B> {option option ...}</I>
<BR> list of options to remove
<LI><I><B>rename</B> {option name option name ...}</I>
<BR>list of options to rename
<LI><I><B>prefix</B> {prefix option option ...}</I>
<BR>pefix all <I>option</I> by <I>prefix</I>
<LI><I><B>initialize</B> {option value option value ...}</I>
<BR>default value of options
<LI><I><B>readonly</B> {option value option value ...}</I>
<BR>new readonly flag
</UL></UL>
</DD></DL>
<DL><DT><A NAME="cget">Widget::<B>cget</B></A>
 <I>path</I>
 <I>option</I>
</DT><DD>

Returns the value of <I>option</I> of BWidget <I>path</I>. <B>cget</B> tests the option
existence and takes care of synchronization with subwidget.
Typically called by the BWidget <B>cget</B> command.

</DD></DL>
<DL><DT><A NAME="configure">Widget::<B>configure</B></A>
 <I>path</I>
 <I>options</I>
</DT><DD>
Description text
</DD></DL>

<DL><DT><A NAME="create">Widget::<B>create</B></A>
 <I>class</I>
 <I>path</I>
 ?<I>rename</I>?
</DT><DD>
    The standard method for creating a BWidget.  The real widget path
    is renamed to $path:cmd, and a new proc is created to replace the
    path which points to the BWidget's commands.

    <p>
    If <i>rename</i> is false, the path will not be renamed, but the
    proc will still be created.  This is useful when inheriting another
    BWidget who will already have renamed the widget.
    </p>

    <p>
    The command returns the widget path.  This command is usually the
    last command executed in the ::create command for the widget.
    </p>
</DD></DL>

<DL><DT><A NAME="declare">Widget::<B>declare</B></A>
 <I>class</I>
 <I>optlist</I>
</DT><DD>

This command declare new resources for a BWidget.
<UL>
<LI><I>class</I> is class of the new widget
<LI><I>options</I> is the list describing new options. Each new option is a list
<B>{option type value ro ?args?}</B> where:
<UL>
<LI><I>option</I> is the name of the option
<LI><I>type</I> is the type of the option
<LI><I>value</I> is the default value of the option
<LI><I>ro</I> is the readonly flag of the option
<LI><I>args</I> depends on type
</UL></UL>
<BR>
<I>type</I> can be:
<BR>
<DL>
<DT><B>TkResource</B></DT>
<DD>
<I>value</I> of <I>option</I> denotes a resource of a Tk widget. <I>args</I> must be <I>class</I> or
<I>{class realoption}</I>. <I>class</I> is the creation command of the Tk widget, e.g.
<B>entry</B>.
The second form must be used if <I>option</I> has not the same name in Tk widget,
but <I>realoption</I>.
<BR>If <I>value</I> is empty, it is initialized to the default value of the Tk widget.
</DD>

<DT><B>BwResource</B></DT>
<DD>
<I>value</I> of <I>option</I> denotes a resource of a BWidget. <I>args</I> must be <I>class</I> or
<I>{class realoption}</I>. <I>class</I> is the name of the namespace of the BWidget, e.g.
<B>LabelFrame</B>.
The second form must be used if <I>option</I> has not the same name in BWidget,
but <I>realoption</I>.
<BR>If <I>value</I> is empty, it is initialized to the default value of the BWidget.
</DD>

<DT><B>Int</B></DT>
<DD><I>value</I> of <I>option</I> is an integer.
<I>args</I> can be <I>{?min? ?max?}</I> to force it to be in a range. The test is
<I>[expr $option &gt; $min] && [expr $option &lt; $max]</I> so
if args is <I>{0 10}</I>, value must be beetween 0 and 10 exclude,
if <I>args</I> is <I>{=0 =10}</I> , value must be beetween 0 and 10 include.
</DD>

<DT><B>Boolean</B></DT>
<DD><I>value</I> of <I>option</I> is a boolean. True values can be <B>1</B>, <B>true</B> or <B>yes</B>.
False values can be <B>0</B>, <B>false</B> or <B>no</B>. <B>Widget::cget</B> always return
0 or 1.
</DD>

<DT><B>Enum</B></DT>
<DD>
<I>value</I> of <I>option</I> is a element of a enumeration. <I>args</I> must be the list
of enumeration, e.g. <I>{top left bottom right}</I>.
</DD>

<DT><B>Flag</B></DT>
<DD>
<I>value</I> of <I>option</I> is a combination of a set of chars. <I>args</I> must be a
string defining the set.
</DD>

<DT><B>String</B></DT>
<DD>
<DD><I>value</I> of <I>option</I> is any uncontrolled string.
</DD>

<DT><B>Synonym</B></DT>
<DD>
<DD><I>option</I> is a synonym of option <I>args</I>. <I>value</I> has no effect here.
</DD>
</DL>
</DD></DL>

<DL><DT><A NAME="define">Widget::<B>define</B></A>
 <I>class</I>
 <I>filename</I>
 ?<I>class ...</I>?
</DT><DD>

    <p>
    This command is used to define a new BWidget class.  It is
    usually the first command executed in a new widget definition.
    </p>

<ul>
    <li><i>class</i> is the name of the new widget class.</li>
    <li><i>filename</i> is the name of the file (without extension) in the
    BWidget distribution that defines this class.</li>
</ul>

    <p>
    Each class defined after the filename is a class that this widget
    depends on.  The ::use command will be called for each of these
    classes after the new widget has been defined.
    </p>

    <p>
    This command does several things to setup the new class.  First, it
    creates an alias in the global namespace for the name of the class
    that points to the class's ::create subcommand.  Second, it defines
    a ::use subcommand for the class which other classes can use to load
    this class on the fly.  Lastly, it creates a default binding to the
    &lt;Destroy&gt; event for the class that calls Widget::destroy on
    the path.  This is the default setup for almost all widgets in the
    BWidget package.
    </p>

</DD></DL>

<DL><DT><A NAME="destroy">Widget::<B>destroy</B></A>
 <I>path</I>
</DT><DD>
Description text
</DD></DL>
<DL><DT><A NAME="focusNext">Widget::<B>focusNext</B></A>
 <I>w</I>
</DT><DD>
Description text
</DD></DL>
<DL><DT><A NAME="focusOK">Widget::<B>focusOK</B></A>
 <I>w</I>
</DT><DD>
Description text
</DD></DL>
<DL><DT><A NAME="focusPrev">Widget::<B>focusPrev</B></A>
 <I>w</I>
</DT><DD>
Description text
</DD></DL>
<DL><DT><A NAME="generate-doc">Widget::<B>generate-doc</B></A>
 <I>dir</I>
 <I>widgetlist</I>
</DT><DD>
Description text
</DD></DL>
<DL><DT><A NAME="generate-widget-doc">Widget::<B>generate-widget-doc</B></A>
 <I>class</I>
 <I>iscmd</I>
 <I>file</I>
</DT><DD>
Description text
</DD></DL>
<DL><DT><A NAME="getoption">Widget::<B>getoption</B></A>
 <I>path</I>
 <I>option</I>
</DT><DD>

Returns the value of <I>option</I> of BWidget <I>path</I>. This command does not test
option existence, does not handle synonym and does not take care of synchronization with
subwidget.

</DD></DL>
<DL><DT><A NAME="getVariable">Widget::<B>getVariable</B></A>
 <I>path</I>
 <I>varName</I>
 <I>?myVarName?</I>
</DT><DD>

<p>
Make the variable <i>varName</i> relational to <i>path</i> accessible in
the current procedure.  The variable will be created in the widget namespace
for <i>path</i> and can be used for storing widget-specific information.
When <i>path</i> is destroyed, any variable accessed in this manner will be
destroyed with it.
</p>

<p>
If <i>myVarName</i> is specified, the variable will be accessible in the
current procedure as that name.
</p>

</DD></DL>
<DL><DT><A NAME="hasChanged">Widget::<B>hasChanged</B></A>
 <I>path</I>
 <I>option</I>
 <I>pvalue</I>
</DT><DD>
Description text
</DD></DL>
<DL><DT><A NAME="init">Widget::<B>init</B></A>
 <I>class</I>
 <I>path</I>
 <I>options</I>
</DT><DD>
Description text
</DD></DL>
<DL><DT><A NAME="setoption">Widget::<B>setoption</B></A>
 <I>path</I>
 <I>option</I>
 <I>value</I>
</DT><DD>

Set the value of <I>option</I> of BWidget <I>path</I> without option test, subwidget mapping,
synonym handling and does not set the modification flag.

</DD></DL>
<DL><DT><A NAME="subcget">Widget::<B>subcget</B></A>
 <I>path</I>
 <I>subwidget</I>
</DT><DD>

Returns the list of all option/value of BWidget <I>path</I> that are mapped to <I>subwidget</I>.

</DD></DL>
<DL><DT><A NAME="syncoptions">Widget::<B>syncoptions</B></A>
 <I>class</I>
 <I>subclass</I>
 <I>subpath</I>
 <I>options</I>
</DT><DD>

This command synchronize options value of a subwidget.
Used when an option of a subwidget is modified out of the BWidget <B>configure</B> command.
<UL>
<LI><I>class</I> is the class of the new BWidget
<LI><I>subclass</I> is the class the subwidget (BWidget class, e.g Entry, or empty for Tk widget)
<LI><I>subpath</I> is the path of the subwidget
<LI><I>options</I> is the list <I>{option realres ...}</I> of options to synchronize 
with subwidget
</UL>
</DD></DL>
<DL><DT><A NAME="tkinclude">Widget::<B>tkinclude</B></A>
 <I>class</I>
 <I>tkwidget</I>
 <I>subpath</I>
 ?<I>arg...</I>?
</DT><DD>

This command includes into a new BWidget the resources of a Tk widget.
Arguments are:
<UL>
<LI><I>class</I> class of the new widget
<LI><I>tkwidger</I> command name of the Tk widget to be included
<LI><I>subpath</I>  path of the widget to configure when BWidget is configured
<LI><I>options</I> is:
<UL>
<LI><I><B>include</B> {option option ...}</I>
<BR>list of options to include (all if not defined)
<LI><I><B>remove</B> {option option ...}</I>
<BR>list of options to remove
<LI><I><B>rename</B> {option name option name ...}</I>
<BR>list of options to rename
<LI><I><B>prefix</B> {prefix option option ...}</I>
<BR>pefix all <I>option</I> by <I>prefix</I>
<LI><I><B>initialize</B> {option value option value ...}</I>
<BR>default value of options
<LI><I><B>readonly</B> {option value option value ...}</I>
<BR>new readonly flag
</UL></UL>
</DD></DL>
</BODY></HTML>
